Shareware Grab Bag

home *** CD-ROM | disk | FTP | other *** search

/ Shareware Grab Bag / Shareware Grab Bag.iso / 007 / qbware.arc / QBWARE.DOC next >

Wrap

Text File | 1988-04-02 | 145.9 KB | 8,185 lines

Q B W A R E / 1 THE QUICKBASIC INTERFACE LIBRARIES Version 1.10 R E F E R E N C E M A N U A L AJM Software P.O. Box 5303 Arvada, Co. 80005-0303 Copyright (c) 1987 AJM Software All Rights Reserved TABLE OF CONTENTS I. Introduction to QBWARE/1 ............................ 2 II. A word about User supported software ................ 3 III. Warranty Information ................................ 5 IV. Registration and License Information ................ 6 V. Product Support ..................................... 10 VI. Using QBWARE/1 ...................................... 11 VII. PRECAUTIONS (READ THIS SECTION) ..................... 14 VIII. BIOS Video Services ................................. 15 IX BIOS Keyboard Services .............................. 25 X. BIOS Diskette Services .............................. 32 XI. BIOS Miscellaneous Services ......................... 39 XII. BIOS AT Disk Services ............................... 46 XIII. File Attribute Services ............................. 56 XIV. File Access Services ................................ 64 XV. DOS Replacement Services ............................ 74 XVI. Miscellaneous DOS services .......................... 87 XVII. The Print Spooler ................................... 97 XVIII. DOS Memory Management ............................... 103 Appendices ................................................. 108 Copyright (c) 1987, AJM Software -Page 1- Introduction to QBWARE/1 QBWARE/1 is a comprehensive set of callable routines that provide easy to use extensions to QuickBasic. The DOS subroutines are specifically designed to provide an easy to use interface between Quickbasic programs and certain DOS facilities that would normally be unavailable to a Quick- basic program. These include access to the DOS print spooler and memory management routines. It is very important to read the manual before using any of these services, as proper setup is important. The BIOS subroutines are specifically designed to provide an easy to use interface between Quickbasic programs and your computer's Basic Input/Output System (BIOS). The system BIOS is a collection of programs that control most of the fundamental processes or functions of your com- puter such as system startup or initialization, communications with per- ipheral devices such as video, disks, modems, printers, etc., handling of certain error conditions such as Ctrl-Break, Divide by zero, and others. Some of the services presented here are already provided in Quickbasic and many of them are not. They will provide you with a greater degree of con- trol over the environment in which your program executes as well as per- forming these services much more quickly. The file management subroutines are specifically designed to provide an easy to use interface between Quickbasic programs and the DOS File Manage- ment services. DOS File Management services are a layer of software that sit between your program and the computer's diskette or hard drive. You must keep in mind that many of these routines interact with your com- puter's BIOS and have been designed and tested on IBM and COMPAQ comput- ers. In order for them to function properly, your computer must be an IBM or Compatible. These functions have been tested with version 2, 2.01, 3 and version 4 of Quickbasic. Quickbasic is a registered trademark of Microsoft. Copyright (c) 1987, AJM Software -Page 2- A Word about User-supported Software User-supported software is a means for the computing community to receive quality software while directly supporting software authors. It is based on the ideas that: The value and utility of software is best assessed by the user on his or her own system. Only after using a program can one really determine whether it serves personal applications, needs and tastes. The creation of independent personal computer software can and should be supported by the computing community. Copying of programs should be encouraged, rather than restricted. The ease with which software can be distributed outside traditional commercial channels reflects the strength, rather than the weakness, of electronic information. Under the user supported concept, anyone may request a copy of a user-supported program by sending a blank, formatted disk to the program author together with an addressed, postage-paid return mailer. A copy of the program, along with documentation on disk, will be sent by return mail on the user's disk. The program carries a notice suggesting registration for the program. You should register if you are going to use the program on a regular basis. Regardless of whether you register and use the program, you are encouraged to copy and distribute the program for the private, non-commercial, trial use of others. User supported software is generally not public domain material; most programs of this nature carry a copyright notice. Rather, the author has licensed you to copy and use the program under certain conditions. Likewise, user supported software is not intended to be free software; it is an experiment in economics, not altruism. It is intended to provide quality software at a low price, while directly supporting the author, without the overhead of distributors, dealers and advertising that produces $500 software packages. User supported software is having a hard time. More and more packages are being taken out of this market, and offered as more traditional, and expensive, products. The reason for this is simple: lots of people are using the packages but very few are paying for them. And without the support of the users, there is absolutely no incentive for software authors to provide their programs in this fashion. Copyright (c) 1987, AJM Software -Page 3- There are many good reasons to register. Besides supporting the author (that is, paying for the software you use), you generally get better support and receive mailed notification of updates and other products. In conclusion, if you regularly use a user supported program (sometimes called Freeware or Shareware) and have not sent in a registration to the author, please do so now. Only through the financial support of users will this kind of inexpensive software continue to be available. Copyright (c) 1987, AJM Software -Page 4- WARRANTY AJM Software makes no warranty of any kind, express or implied, including without limitation, any warranties of merchantability and/or fitness for a particular purpose. AJM Software shall not be liable for any damages, whether direct, indirect, special or consequential arising from a failure of this program to operate in the manner desired by the user. AJM Software shall not be liable for any damage to data or property which may be caused directly or indirectly by use of the program. IN NO EVENT WILL AJM Software BE LIABLE TO YOU FOR ANY DAMAGES, INCLUDING ANY LOST PROFITS, LOST SAVINGS OR OTHER INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF YOUR USE OR INABILITY TO USE THE PROGRAM, OR FOR ANY CLAIM BY ANY OTHER PARTY. Copyright (c) 1987, AJM Software -Page 5- Registration and ordering information A QBWARE/1 registration licenses you to use the product on a regular basis. Registration includes mailed notification of updates and priority support. Users need register only one version of QBWARE/1 - registration includes licensed use of all upgrades. Individual registrations for QBWARE/1 are available from AJM Software at a cost of $39.00. AJM will provide you with the most current release of QBWARE/1 in both object and assembly source code form on 5 1/4 inch diskette or 3 1/2" diskette. The reference manual will also be included on the diskette. Registration entitles you to include any QBWARE/1 routine in your applications for distribution without royalty. Including QBWARE/1 in your applications without registration is strictly prohibited. Quantity discounts are available. Please see the section titled 'Corporate and quantity purchases'. In addition, evaluation disks are available at any time for $10. These disks do not include registration. The fee covers diskette, postage and handling. Please use the enclosed order form when placing an order. ORDERS OUTSIDE THE US: Please include an additional $10.00 to cover additional postage and handling costs. No C.O.D.'s will be accepted on orders delivered outside the US. Copyright (c) 1987, AJM Software -Page 6- Remit to: AJM Software Order Form P.O. Box 5303 Arvada, CO 80005-0303 Please send: ____ QBWARE/1 Disk (Evaluation only) ........... @ $ 10.00 ea $ ______ (includes all routines in .QLB form and manual on disk) ____ QBWARE/1 Registration ..................... @ $ 39.00 ea $ ______ (includes QBWARE/1 disk and source code) Subtotal ______ Please check appropriate version Less Discount <______> QB V2 ____ C.O.D. Fee ($5.00) ______ QB V3 ____ 3 1/2" Disk ($5.00) ______ QB V4 ____ Total $ ______ Payment by: ( ) Check ( ) C.O.D. Name: ____________________________________________________________ Company: ____________________________________________________________ Address: ____________________________________________________________ : ____________________________________________________________ : ____________________________________________________________ Day Phone: _________________________ Eve: ___________________________ ORDERS OUTSIDE THE US: Please include an additional $10.00 to cover additional postage and handling costs. No C.O.D.'s will be accepted on orders delivered outside the US. Copyright (c) 1987, AJM Software -Page 7- Corporate and Quantity Purchases All corporate, business, government or other commercial users of QBWARE/1 must be registered. We offer quantity discounts starting at the sixth copy. Orders in quantities of less than 50 units are handled as bulk purchases. Purchases of over 50 units may be handled as quantity purchases or as corporate licensing agreements. Licensing agreements allow duplication and distribution of specific numbers of copies within the licensed institution. Duplication of multiple copies is not allowed except through execution of a licensing agreement. Please write for details. The quantity purchase discounts are as follows: 0- 5 copies: no discount 6- 20 copies: 20% discount 21+ copies: 40% discount ALL PRICES AND DISCOUNTS ARE SUBJECT TO CHANGE WITHOUT NOTICE. Discounts are not cumulative; they apply to single orders of like products only. Unit prices are the same as for individual users. WARNING: YOU MAY NOT USE QBWARE/1 WITHIN YOUR ORGANIZATION WITHOUT A PRIOR PURCHASE OR LICENSE ARRANGEMENT. Copyright (c) 1987, AJM Software -Page 8- LICENSE All versions of QBWARE/1, including version 1.0, are not public domain software, nor are they free software. QBWARE/1 is copyright (C) 1987 by AJM Software Non-registered users are granted a limited license to use QBWARE/1 on a trial basis for the purpose of determining whether it is suitable for their needs. Use of QBWARE/1, except for this limited purpose, requires registration. Use of non-registered copies of QBWARE/1 by any person, business, corporation, governmental agency or other entity institution is strictly forbidden. Registration permits a user the license to use QBWARE/1 for development purposes, only on a single computer. QBWARE/1 can be included into any program and distributed in library form only without royalty. A registered user may use the program on a different computer, but may not use the program on more than one computer at the same time. All users are granted a limited license to copy QBWARE/1 only for the trial use of others subject to the above limitations, and also the following: QBWARE/1 must be copied in unmodified form, complete with the file containing this license information. The full QBWARE/1 documentation must be included with the copy. No fee, charge or other compensation may be accepted or requested by any licensee, except a handling fee not to exceed $10.00 QBWARE/1 may not be distributed in conjunction with any other product. The ASSEMBLY source code for QBWARE/1 may NOT be distributed under any circumstances. The object modules supplied with a registered copy of QBWARE/1 may NOT be distributed under any circumstances. Operators of electronic bulletin board systems (Sysops) may post QBWARE/1 for downloading by their users only as long as the above conditions are met. Distributors of public domain or user supported software, other than operators of electronic bulletin board systems, may distribute copies of QBWARE/1 subject to the above conditions only after obtaining written permission from AJM Software. Copyright (c) 1987, AJM Software -Page 9- Product Support If you have any questions or comments about the use of QBWARE/1, please fill out a problem log and send it to us. In your note, describe as completely as possible the problem you are having. Let us know your machine configuration, which routine you are questioning, the version of QBWARE/1, and any resident software installed. If possible, include a copy (on paper) of your source code. Describe what steps you take before the problem occurs, and exactly what the program does when it occurs. If you do not provide us with a complete description of the problem there is little we can do to help. We'll do our best to get you past the problem, but if you are not a registered user we do not guarantee to provide support of any kind. Please be patient. We usually respond to registered users within 3 working days at the most. We will provide support to non-registered users at our discretion. It generally depends on how the request is worded and the mental disposition of the staff person assigned to handle requests on that day. Copyright (c) 1987, AJM Software -Page 10- Using QBWARE/1 QuickBasic versions 2, 2.01, 3 All of the QBWARE/1 routines can be accessed via the Quickbasic 'Call' statement. The format of this statement is as follows: Call Function(Parm1%, Parm2%, Parm3$) Function is the name of the routine to be executed. It must be spelled exactly as shown in the following chapters. The parameters to be passed to the routine will also be explained in the following chapters. You must use the exact number of parameters shown in each function description and each parameter must be the type (i.e. character or integer) shown in each function description. Using an incorrect number of parameters or using a parameter of the wrong type (i.e. using character instead of integer) will generally result in the abnormal termination of your program. Usually you will get either a 'String Space Corrupt' error or you will start executing the wrong statements in your program. In any event, it is almost impos- sible to predict the results of these two types of errors, so it is criti- cal that you be very careful in coding the call statements. The parameters passed to QBWARE/1 routines will be either character or numeric integers. There are no special requirements for passing integers and constants may also be used. There is no functional difference between these two sets of statements: Example 1 Drive$ = "A" 'Indicate drive a Vol$ = "DISK LABEL " 'New volume label Call FlPVol(Drive$, Vol$, Rc%) 'Call QBWARE/1 routine Example 2 Call FlPVol("A", "DISK LABEL ", Rc%) Note that Rc% must not be defined as a constant because the QBWARE routine will return a value in this field and your Quickbasic program cannot access this field if it is defined as a constant. All character fields must be initialized to the proper length before calling a QBWARE/1 func- tion. Failing to do so may result in a 'String Space Corrupt' condition. The following two examples appear similar but Example 1 will fail and Example 2 will succeed because 'Char$' has been properly initialized. Example 1 (incorrect) Char$ = "" 'clear work field Call FlGDrv(Char$) 'get the current drive Copyright (c) 1987, AJM Software -Page 11- Example 2 (correct) Char$ = space$(1) 'clear work field Call FlGDrv(Char$,) 'get the current drive Including the QBWARE/1 routines in your programs can be accomplished in a variety of ways. The non-registered user can do one of the following: 1) compile the program from within the Quickbasic interactive develop- ment environment 2) compile the program from the DOS prompt In order to use method 1, place the file QBWARE.EXE in the directory con- taining your Quickbasic files (i.e. QB.EXE and BRUN20.LIB). When starting Quickbasic, enter the following command at the DOS prompt: QB /L QBWARE.EXE You may now use any of the QBWARE.LIB functions in your programs. If you compile your program using the 'Exe' output option, the appropriate QBWARE.LIB functions will be available to the EXE file. In order to use method 2, place the file QBWARE.EXE in the directory con- taining your Quickbasic system files. The following example shows how to create an executable file from the Basic source code in the file 'FILECHK.BAS': QB FILECHK /L QBWARE.EXE; LINK FILECHK; Doing this will create the executable file 'FILECHK.EXE' Additionally, registered users will have the ability to create their own custom user library (see the file BUILDLIB.SCR on the QBWARE.LIB disk for instructions) or they can include the appropriate functions into their program when it is linked. For example, if the program 'TEST.BAS' uses the QBWARE/1 routines DOSVER and BOOT, an executable file can be created using the following commands at the DOS prompt: QB TEST; LINK TEST DOSVER BOOT; This assumes that all of the files on the QBWARE.LIB disk have been placed into the directory containing the Quickbasic system files. Copyright (c) 1987, AJM Software -Page 12- Using QBWARE/1 QuickBasic version 4 Parameter passing is pretty much the same under QB4 with a single excep- tion. Arrays are handled a little differently. When passing entire arrays to the QBWARE/1 routine, use VARPTR. QB2 Call FlFind(Count%, DirList$(LBound(DirList$))) QB4 Call FlFind(Count%, VARPTR(DirList$(LBound(DirList$)))) Using VARPTR will insure compatibility in compiling from within the QB4 environment and from the DOS prompt. When starting QuickBasic V4 enter the following: QB /L QBWARE This automatically loads the QBWARE/1 quick library into the QB$ environ- ment. To compile from the DOS prompt, do the following: BC PROGNAM; LINK /EX /NOE PROGNAM,,,BRUN40 QBWARE; or BC PROGNAM /O; LINK /EX /NOE PROGNAM,,,BCOM40 QBWARE IN ORDER TO ACHIEVE CONSISTENT RESULTS, ALWAYS CREATE YOUR EXE FILES AS DESCRIBED ABOVE. IN QB4, YOU CANNOT CREATE AN EXE FILE USING THE QBWARE/1 ROUTINES FROM THE QB ENVIRONMENT. YOU MUST DO THIS FROM THE DOS PROMPT. Copyright (c) 1987, AJM Software -Page 13- PRECAUTIONS!!!!!! These routines were designed to used with Quickbasic on an IBM PC or com- patible computer. Using this product with any Basic compiler or inter- preter other than Quickbasic version 2 or 3 will probably not work and may cause loss of data. Using this product on a non-IBM compatible computer will give hit or miss results. Some things will work, some things won't work. The only way to find out is to try. A SPECIAL NOTE ABOUT HARD DISKS - there are many manufacturers and vari- eties of hard disks available for the IBM PC and compatible computer. Many of these hard disks work through the traditional BIOS functions and many provide their own proprietary software to function properly. These disks with proprietary software may not respond properly to some of the BIOS interface routines. IN ANY EVENT, DO NOT TEST ANY HARD DISK OR FLOPPY DISK ROUTINES WITHOUT FIRST BACKING UP YOUR DISK - REPEAT - DO NOT TEST ANY HARD DISK OR FLOPPY DISK ROUTINES WITHOUT FIRST BACKING UP YOUR DISK. Copyright (c) 1987, AJM Software -Page 14- The BIOS Video Services Function Summary BSVMODE - Get or set video mode BSVSCUR - Set or get cursor size BSVSWID - Get screen width BSVSPOS - Get or set cursor position BSVSPAG - Get or set video display page BSVSCRUP - Scroll up or clear a window BSVSCRDN - Scroll down or clear a window BSVRCHR - Read a character and attribute from the screen BSVWCHR - Write a character to the screen BSVWTTY - Write in teletype mode Copyright (c) 1987, AJM Software -Page 15- BSVMODE - Get or set video mode Usage - Call BsVMode(Function%, Mode%) Function% 0 - set video mode 1 - get video mode Mode% (When Function% = 0, Mode% must be initialized to one of the following values. When Function% = 1, Mode% will return one of the following values.) Mode Type Adapter 0 40 X 25 B/W text CGA 1 40 X 25 16 color text CGA 2 80 X 25 B/W text CGA 3 80 X 25 16 color text CGA 4 320 X 200 4 color graphics CGA 5 320 X 200 4-Grey graphics CGA 6 640 X 200 B/W graphics CGA 7 80 X 25 B/W text MA(Monochrome) 8 160 X 200 16 color graphics PCjr 9 320 X 200 16 color graphics PCjr 10 640 X 200 4 color graphics PCjr 10 640 X 200 16 color graphics EGA 13 320 X 200 4 color graphics EGA 14 640 X 200 16 color graphics EGA 15 640 X 350 4 color graphics EGA 16 640 X 350 4 or 16 color graphics EGA Programming notes: For RGB monitors, there is no functional difference between modes 0 and 1, or between modes 2 and 3. The EGA will support all modes except 8 and 9. Normally, the screen buffer will be cleared when you set the video mode - even if you set it the same mode. This is not, however, a recommended method for clearing the screen as it could cause some delay in many PC- compatibles. Using a mode that is not supported by your video adapter card will have unpredictable results. Copyright (c) 1987, AJM Software -Page 16- BSVSCUR - Set or get cursor size Usage - Call BsVSCur(Function%, Start%, End%) Function% 0 - set cursor size 1 - get cursor size Start% Starting scan line End% Ending scan line Programming notes: The scan line is a row of pixels that make up a character on the screen. On monochrome monitors, there are 13 scan lines numbered 0 thru 12. On RGB monitors, there are 8 scan lines numbered 0 thru 7. The default val- ues for cursor size are as follows: Mode Display Start End 0-3 RGB Monitor (text modes) 6 7 7 Monochrome 11 12 The hardware causes the cursor to blink and it normally cannot be dis- abled while in text mode, however, some machines will cause the cursor to disappear when a starting scan line of 32 is used. A technique that always makes the cursor disappear is to move it off the screen using BSVSPOS (e.g. move it to column 1, row 26). Using a starting scan line that is greater than the ending scan line will make the cursor wrap and cause a two-part cursor to show on the screen. Function% must be initialized prior to calling BSVSCUR. If function% is 0 then Start% and End% must be initialized to proper values prior to making the call. Copyright (c) 1987, AJM Software -Page 17- BSVSWID - Get screen width Usage - Call BsVSWid(Wid%) Wid% Number of characters that can be displayed on the screen - either 40 or 80. BSVSPOS - Get or set cursor position Usage - Call BsVSPos(Function%, Row%, Column%, Page%) Function% 0 - set cursor position 1 - get cursor position Row% Cursor coordinate Column% Cursor coordinate Page% Display page whose cursor position is to be set or retrieved. Programming notes: A separate cursor is maintained for each display page (See BSVSPAG for more on display pages). The cursor is affected only in the display page specified. Coordinates (1,1) represent the upper left hand corner of the screen. Coordinates (80,25) represent the lower right-hand corner of the screen. Positioning the cursor outside the limits of the current display will cause the cursor to disappear. In graphics modes, Row% and Column% should be interpreted as pixel coordi- nates. Function% and Page% must be initialized prior to calling BSVSPOS. If Function% is 0 then Row% and Column% must be initialized prior to making the call. Copyright (c) 1987, AJM Software -Page 18- BSVSPAG - Get or set video display page Usage - Call(BsVSPag(Function%, Page%) Function% 0 - set current page 1 - get current page Programming Notes: Valid page ranges are as follows: Page range Mode Adapter 0 - 7 0 CGA 0 - 7 1 CGA 0 - 3 2 CGA 0 - 3 3 CGA 0 - 7 2 EGA 0 - 7 3 EGA 0 - 7 13 EGA 0 - 3 14 EGA 0 - 1 15 EGA 0 - 1 16 EGA Changing pages has no effect on their contents and text can be written to any page regardless of which page is active. Using multiple pages is not possible on a monochrome monitor with an MDA adapter. Function% must be initialized to 0 or 1 prior to calling BSVSPAG. If Function% is 0 then Page% must be initialized to a valid page number. Copyright (c) 1987, AJM Software -Page 19- BSVSCRUP - Scroll up or clear a window Usage - Call BsVScrup(Lines%, FgColor%, BgColor%, Ulc%, Ulr%, Lrc%, Lrr%) Lines% Number of lines to scroll up. If Lines% is zero, then the entire window is blanked. FgColor% Foreground color - 0 thru 31 are valid foreground colors. BgColor% Background color - 0 thru 7 are valid background colors. Ulc% Coordinate of the left column of the scroll window. 1 indicates the far left column. Ulr% Coordinate of the top row of the scroll window. 1 indi- cates the top row of the screen. Lrc% Coordinate of the right column of the scroll window. 80 is the far right column. Lrr% Coordinate of the bottom row of the scroll window. 25 is the last row of the screen. Programming notes: This function affects only the currently active display page and any data scrolled off of the window is lost. Blank lines are inserted at the bot- tom of the window. If the number of lines to scroll equals zero, then the entire window is blanked out. All fields must be initialized prior to calling BSVSCRUP. Copyright (c) 1987, AJM Software -Page 20- BSVSCRDN - Scroll down or clear a window Usage - Call BsVScrdn(Lines%, FgColor%, BgColor%, Ulc%, Ulr%, Lrc%, Lrr%) Lines% Number of lines to scroll down. If Lines% is zero, then the entire window is blanked. FgColor% Foreground color - 0 thru 31 are valid foreground colors. BgColor% Background color - 0 thru 7 are valid background colors. Ulc% Coordinate of the left column of the scroll window. 1 indicates the far left column. Ulr% Coordinate of the top row of the scroll window. 1 indi- cates the top row of the screen. Lrc% Coordinate of the right column of the scroll window. 80 is the far right column. Lrr% Coordinate of the bottom row of the scroll window. 25 is the last row of the screen. Programming notes: This function affects only the currently active display page and any data scrolled off of the window is lost. Blank lines are inserted at the top of the window. If the number of lines to scroll equals zero, then the entire window is blanked out. All fields must be initialized prior to calling BSVSCRDN. Copyright (c) 1987, AJM Software -Page 21- BSVRCHR - Read a character and attribute from the screen Usage - Call BsVRChr(Char$, FgColor%, BgColor%, Row%, Col%, Page%) Char$ Character read from the screen. FgColor% Foreground color BgColor% Background color Row% Coordinate of the character to read from the screen. Col% Coordinate of the character to read from the screen. Page% Display page to read Programming notes: Char$ should be initialized to a single space prior to using this service. Copyright (c) 1987, AJM Software -Page 22- BSVWCHR - Write a character to the screen Usage - Call BsVWChr(Char$, FgColor%, BgColor%, Row%, Col%, Page%) Char$ Character to write to the screen. FgColor% Foreground color BgColor% Background color Row% Coordinate of the character to write to the screen. Col% Coordinate of the character to write to the screen. Page% Display page to be written to Programming notes: All fields should be properly initialized before using this service. The current cursor position is not affected by this service. Copyright (c) 1987, AJM Software -Page 23- BSVWTTY - Write in teletype mode Usage - Call BsVWTTY(Text$, FgColor%, BgColor%) Text$ Text to be written to the screen. FgColor% Foreground Color BgColor Background color Programming notes: This service recognizes special ASCII codes for bell, line feed, and back- space. Any other characters are written to the screen and the cursor position is advanced appropriately. Do not mix this service with BASIC PRINT statements as the cursor posi- tioning will be inconsistent. Copyright (c) 1987, AJM Software -Page 24- The BIOS Keyboard Services Function Summary BSKGET - Get a character from the keyboard BSKSTAT - Determine the status of the toggle keys BSKCLR - Clear the keyboard buffer BSKNXT - Preview the keyboard buffer BSKSTOG - Set keyboard toggles BSKTOGH - Determine whether toggle keys are pressed Copyright (c) 1987, AJM Software -Page 25- BSKGET - Get a character from the keyboard Usage - Call BsKGet(Char$, Scancode%) Char$ The character entered at the keyboard. Scancode% The scan code of the character entered at the keyboard. A partial list of scancodes is provided in Appendix A. Programming notes: This function retrieves the next character in the keyboard buffer. If there is nothing in the buffer, it will wait until a character is ready and thereby suspend program execution. BSKNXT, discussed later, will allow you to peek into the keyboard buffer to determine if a key has been pressed without suspending the program. Char$ will either the standard ASCII code of the key pressed or CHR$(0) if a special key was pressed (i.e. the function keys, PgUp, Home, etc.). If Char$ is a CHR$(0), then Scancode% will indicate which key was pressed. See Appendix A for a list of scancodes. Copyright (c) 1987, AJM Software -Page 26- BSKSTAT - Determine the status of the toggle keys Usage - Call BsKStat(Insert%, Caps%, Num%, Scroll%, Alt%, Ctrl%, LShift%, RShift%) Programming notes: For Insert%, Caps%, Num%, and Scroll% - If the returned value is 1, then that mode has been toggled on (i.e. - Caps light is on). If the value returned is 0, then that mode has been toggled off. For Alt%, Ctrl%, LShift%, RShift% - If the returned value is 1, then that key is currently depressed. If the value is 0, then that key is not depressed. Copyright (c) 1987, AJM Software -Page 27- BSKCLR - Clear the keyboard buffer Usage - Call BsKClr Programming notes: BSKCLR is not passed any parameters, nor does it return any values. It simply clears any keystrokes that have not been read into your program but are waiting in the keyboard buffer. Copyright (c) 1987, AJM Software -Page 28- BSKNXT - Preview the keyboard buffer Usage - Call BsKNxt(Char$, Scancode%, Rc%) Char$ The character entered at the keyboard. Scancode% The scan code of the character entered at the keyboard. A partial list of scancodes is provided in Appendix A. Rc% Return code 0 indicates that no key has been pressed. Return code 1 indicates that a key has been pressed. Programming notes: This function will not remove a character from the keyboard buffer. If the return code indicates that a character is in the buffer, you must use BSKGET to get the character out of the buffer. See notes for BSKGET and Appendix A. Copyright (c) 1987, AJM Software -Page 29- BSKSTOG - Set keyboard toggles Usage - Call BsKSTog(Insert%, Caps%, Num%, Scroll%) Programming notes: Each parameter must be initialized to 0 or 1. If the parameter is ini- tialized to 1 then that toggle will be turned on. If the parameter is 0 then that toggle will be turned off. For example: Call BsKSTog(0,1,1,0) will turn CapsLock and NumLock on, and it will turn ScrollLock and Insert mode off. Copyright (c) 1987, AJM Software -Page 30- BSKTOGH - Determine whether toggle keys are pressed Usage - Call BsKTogH(Insert%, Caps%, Num%, Scroll%) Programming notes: No parameters need to be initialized prior to making this call. If any of the returned values is 1, that indicates that the corresponding key is currently being held down. If any of the returned values is 0, that indi- cates that the corresponding key is not currently being held down. Note that this function does not tell us the status of the toggle keys, only whether or not someone is physically pressing them at that moment. Copyright (c) 1987, AJM Software -Page 31- The BIOS Diskette Services Function Summary BSDSTAT - Get diskette controller status BSDRESET - Reset floppy disk controller BSDVRFY - Verify sectors on a diskette BSDREAD - Read a sector from a diskette BSDWRIT - Write a sector to diskette BSDFMT - Format a track on a diskette *********************** IMPORTANT ************************* Before using any of these functions, please read the documentation care- fully and when testing your programs, please use blank diskettes. These functions will also work with a hard disk, so if you have a hard disk installed, please take extra precautions. Copyright (c) 1987, AJM Software -Page 32- BSDSTAT - Get diskette controller status Usage Call BsDStat(Rc%) Rc% Reason - Diskette drives only 0 Successful 1 Invalid function 2 Address mark not found 3 Write protect error 4 Sector not found 6 Diskette change detected 8 DMA failure 9 DMA boundary overrun 16 bad CRC: parity check 32 controller malfunction 64 seek failure - move to requested track failed 128 time out - drive did not respond (the door is open) Rc% Reason - Hard disk drives only 0 Successful 1 Invalid function 2 Address mark not found 4 Sector not found 5 Reset failed 7 Drive parameter activity failed 9 DMA boundary overrun 10 Bad block flag detected 16 Uncorrectable ECC data error 17 ECC corrected data error 32 controller malfunction 64 seek failure - move to requested track failed 128 time out - drive did not respond 170 Drive not ready 187 Undefined error occured 204 Write fault active 255 Sense operation failed Programming notes: This function always returns the status of the last disk operation. The messages normally seen when accessing a diskette with DOS, such as: Not ready error reading drive a Abort, Retry, Ignore will not be seen when using this function (and any other BIOS diskette function), therefore, you must always determine whether a disk operation has failed or succeeded when using the BIOS disk services. Copyright (c) 1987, AJM Software -Page 33- BSDRESET - Reset floppy disk controller Usage - Call BsDReset Programming notes: This function resets the disk controller and prepares it for I/O. It will force the BIOS diskette support routines to recalibrate the disk drive's read/write head. It should be used only after an error is detected during a disk drive operation. Copyright (c) 1987, AJM Software -Page 34- BSDVRFY - Verify sectors on a disk Usage - Call BsDVrfy(Buffer$, Drive$, Head%, Track%, Sector%, Rc%) Buffer$ Not used for this function. Drive$ Letter designation for to drive containing the diskette to be verified. Head% Cylinder head Track% Track containing sector to be verified. Sector% Relative ID of the sector to be verified. Rc% Return code - see function BSDSTAT Programming notes: For 1.2 Meg drives, the diskette drive parameter table must reflect the type of media installed for correct operation. It is the responsibility of the programmer to ensure that the diskette drive parameter table is correct. Unpredictable results can occur otherwise (See BSDASTYP). This service will verify only a single sector with each call. If needed, the Assembler source can easily be modified to verify more than one sector (up to an entire track). The verify service reads the specified sector and insures that it passes the CRC check. See Appendix C - Miscellaneous diskette information. Copyright (c) 1987, AJM Software -Page 35- BSDREAD - Read a sector from a disk Usage - Call BsDRead(Buffer$, Drive$, Head%, Track%, Sector%, Rc%) Buffer$ The string where the data read from disk will be placed into. Drive$ Letter designation for to drive containing the disk to be read. Head% Cylinder head containing the track to be read. Track% Track containing sector to be read. Sector% Relative ID of the sector to be read. Rc% Return code - see function BSDSTAT Programming notes: It is the responsibility of the programmer to ensure that Buffer$ is long enough to hold the sector read from disk (usually 512 bytes). If it is not long enough, the results are unpredictable. Generally you will see a 'String Space Corrupt' message returned from BASIC. This service will read only a single sector with each call. If necessary, the Assembler source can easily be modified to read more than one sector (up to an entire track). See Appendix C - Miscellaneous diskette information. Copyright (c) 1987, AJM Software -Page 36- BSDWRIT - Write a sector to disk Usage - Call BsDWrit(Buffer$, Drive$, Head%, Track%, Sector%, Rc%) Buffer$ The string containing the data to be written to disk. Drive$ Letter designation for to drive containing the disk to be written Head% Cylinder head containing the track to be written. Track% Track containing sector to be written. Sector% Relative ID of the sector to be written. Rc% Return code - see function BSDSTAT Programming notes: When testing, first backup your diskette. It is very easy to inadver- tently erase usable data or render a diskette unusable with this service. This service will always write a complete sector. If Buffer$ is shorter than the length of a sector (usually 512 bytes), the contents of the sec- tor written will be unpredictable. This service will write only a single sector with each call. If needed, the Assembler source can easily be modified to write more than one sector (up to an entire track). See Appendix C - Miscellaneous diskette information. Copyright (c) 1987, AJM Software -Page 37- BSDFMT - Format a track on a disk Usage - Call BsDFmt(Buffer$, Drive$, Head%, Track%, Sector%, Rc%) Buffer$ The string containing the track format table (See Appen- dix C). Drive$ Letter designation for to drive containing the diskette to be formatted. Head% Cylinder head containing the track to be formatted. Track% Track containing sector to be formatted. Sector% Number of sectors to be formatted. Rc% Return code - see function BSDSTAT Programming notes: For 1.2 Meg drives, the diskette drive parameter table must reflect the type of media installed for correct operation. It is the responsibility of the programmer to ensure that the diskette drive parameter table is correct. Unpredictable results can occur otherwise (See BSDASTYP). When testing, first backup your diskette. It is very easy to inadver- tently erase usable data or render a diskette unusable with this service. This service will always format a complete track. If Sector% is less than the maximum number of sectors that can fit on that track, then the unfor- matted sectors will no longer be available. If you format track 0 on a diskette with this service, the diskette will not be usable until a boot record is written to sector 0. If needed, the Assembler source code can be modified to write a boot record to the dis- kette. Copyright (c) 1987, AJM Software -Page 38- The BIOS Miscellaneous Services Function Summary BSEQPMT - Get installed equipment BSPINIT - Initialize printer BSPSTAT - Get printer status BSPRINT - Print a string of characters BSPRTSC - Print screen Copyright (c) 1987, AJM Software -Page 39- BSEQPMT - Get installed equipment Usage - Call BsEqpmt(RomDate$, RAM%, ExtRAM%, ExpRAM%, Printers%, RS232%, Floppies%, Gameport%, Disks%) RomDate$ ROM-BIOS revision date RAM% Amount, in Kilobytes, of installed RAM. ExtRAM% Amount, in Kilobytes, of extended memory. ExpRAM% Amount, in 16K pages, of LIMM expanded memory. Printers% Number of printer ports installed. Rs232% Number of serial ports installed. Floppies% Number of floppy disk drives installed. Gameport% Number of gameports installed. Disks% Number of hard disks installed. Programming notes: Some of these fields may not be reliable in certain hardware configura- tions. Items to be wary about are RomDate$, ExtRAM%, and in particular, the number of hard disks. Copyright (c) 1987, AJM Software -Page 40- BSPINIT - Initialize printer Usage - Call BsPInit(Printer%, Rc%) Printer% The printer port number - 0 is LPT1, 1 is LPT2, etc. Rc% Return code - see BSPSTAT Programming notes: This service will initialize the printer. That is to say, it will: - Reset top-of-form - Return the printer to its default setup - poll the printer for printer status Copyright (c) 1987, AJM Software -Page 41- BSPSTAT - Get printer status Usage - Call BsPStat(Printer%, Rc%) Printer% The printer port number - 0 is LPT1, 1 is LPT2, etc. Rc% Return code Programming notes: The return code is actually a series of bit settings that indicates the following conditions: - Printer ready - Acknowledge - Out of paper - I/O error (on some printers, this indicates an off-line condition) - Timeout - Selected When checking printer status, the 'selected' indicator tells you that the printer is on-line and ready to go. Some printers will return a "Printer ready' status even when turned off (this, incidentally, is why Quickbasic will occasionally print to a printer that is turned off and never return an error condition). Before issuing an LPRINT (or equivalent) command in Quickbasic, make sure that the printer is selected. ***************************** IMPORTANT ********************************* See the next page for a Quickbasic program segment that properly inter- prets Rc%. Copyright (c) 1987, AJM Software -Page 42- The following code segment will extract the appropriate values. It is included in the sample program archive(Registered owners only). Printer% = 0 'Use LPT1 Call BsPStat(Printer%, Rc%) 'Get status of printer Printer.Ready% = (Rc% and 128) = 128 '1st bit indicates printer ready Acknowledge% = (Rc% and 64) = 64 '2nd bit indicates Ack Out.of.Paper% = (Rc% and 32) = 32 '3rd bit indicates out of paper IO.Error% = (Rc% and 8) = 8 '5th bit indicates I/O Error Timeout% = (Rc% and 1) = 1 '8th bit indicates Timeout Selected% = (Rc% and 16) = 16 '4th bit indicates Selected Locate 1,1: Color 15,1: Cls If Printer.Ready% then Print "Printer at LPT1 reports Ready" End if If Acknowledge% then Print "Printer at LPT1 reports Acknowledge" End if If Out.of.Paper% then Print "Printer at LPT1 reports Out of Paper of Paper jam" End if If IO.Error% then Print "Printer at LPT1 reports I/O error or Printer off-line" End if If Timeout% then Print "Printer at LPT1 has timed out" End if If Selected% then Print "Printer at LPT1 is selected" End if Copyright (c) 1987, AJM Software -Page 43- BSPRINT - Print a string of characters Usage - Call BsPrint(Text$, Printer%, Rc%) Text$ String to print Printer% Printer port Rc% Return code Programming notes: See BSPSTAT for an explanation of return codes. This service sends whatever is in Text$ to the appropriate printer port. All special printer codes such as NewLine, TopofForm, etc, will be inter- preted correctly by the printer. Copyright (c) 1987, AJM Software -Page 44- BSPRTSC - Print screen Usage - Call BsPrtSc Programming notes: This service is the equivalent of pressing the 'PrtSc' key on the key- board. The screen will be printed to LPT1. Copyright (c) 1987, AJM Software -Page 45- The BIOS AT Disk Services Function Summary BSDAPARM - Get current drive parameters BSDATST - Test for drive ready BSDARST - Alternate disk reset BSDARCL - Recalibrate drive BSDADIAG - Perform controller diagnostics BSDASTAT - Detect diskette change BSDATYPE - Get disk type BSDASTYP - Set diskette type BSDASEEK - Position heads over a specified cylinder *********************** IMPORTANT ************************* These functions are documented only for AT type machines. These machines generally use a 1.2 Meg diskette drive whose characteristics are different enough from the 360KB drive to warrant these new BIOS services. These services also provide additional support for hard disks. Copyright (c) 1987, AJM Software -Page 46- BSDAPARM - Get current drive parameters Usage - Call BsDAParm(Drive$, Heads%, Cylinders%, Sectors%) Drive$ Letter designation of the target drive Heads% Maximum number of heads on the disk Cylinders% Maximum number of Cylinders/Head Sectors% Maximum number of Sectors/Cylinder Programming notes: This service will not function on a diskette drive. It is intended for use with a hard disk only. Copyright (c) 1987, AJM Software -Page 47- BSDATST - Test for drive ready Usage - Call DsDATst(Drive$, Rc%) Drive$ Letter designation of the target drive Rc% Return code Programming notes: This service will not function on a diskette drive. It is intended for use with a hard disk only. This service tests the status of the DRIVE READY signal on the selected drive. See BSDSTAT documentation for an explanation of return codes. Copyright (c) 1987, AJM Software -Page 48- BSDARST - Alternate disk reset Usage - Call BsDARst(Drive$, Rc%) Drive$ Letter designation of the target drive Rc% Return code Programming notes: This service is the same as BSDRESET documented earlier except that BSDARST can be used only with hard disk controllers. See BSDSTAT documentation for an explanation of return codes. Copyright (c) 1987, AJM Software -Page 49- BSDARCL - Recalibrate drive Usage - Call BsDARcl(Drive$, Rc%) Drive$ Letter designation of the target drive Rc% Return code Programming notes: This service will not function on a diskette drive. It is intended for use with a hard disk only. This service instructs the specified drive to recalibrate. This is done by seeking track 0. This service should be used only after an error has been detected and before any retries are made. See BSDSTAT documentation for an explanation of return codes. Copyright (c) 1987, AJM Software -Page 50- BSDADIAG - Perform controller diagnostics Usage BsDADiag(Rc%) Rc% Return code Programming notes: This service will not function on a diskette drive. It is intended for use with a hard disk only. This service instructs the hard disk controller to perform its internal diagnostic routines. See BSDSTAT documentation for an explanation of return codes. Copyright (c) 1987, AJM Software -Page 51- BSDASTAT - Detect diskette change Usage - Call BsDAStat(Drive$, Rc%) Drive$ Letter designation of the target drive Rc% Return code Programming notes: This service will detect whether or not the disk drive door has been opened since the last disk operation. It is meaningless for hard drives. This service should be used only with those drives that can detect disk changes (See BSDATYPE). See BSDSTAT documentation for an explanation of return codes. Copyright (c) 1987, AJM Software -Page 52- BSDATYPE - Get disk type Usage - Call BsDAType(Drive$, Rc%) Drive$ Letter designation of the target drive Rc% 0 - drive is not present 1 - diskette without change detection 2 - diskette with change detection% 3 - fixed disk Programming notes: This service will work with both hard and floppy disk drives. Copyright (c) 1987, AJM Software -Page 53- BSDASTYP - Set diskette type Usage - Call BsDASTyp(Drive$, Type%, Rc%) Drive$ Letter designation of the target drive Type% 1 - Double-density drive 2 - 360KB diskette in a 1.2MB drive 3 - 1.2MB diskette in a 1.2MB drive Rc% Return code Programming notes: This service is meaningless for fixed disks. This service should be used prior to all Format and Verify requests to any 1.2MB diskette drives. See BSDSTAT for an explanation of return codes. Copyright (c) 1987, AJM Software -Page 54- BSDASEEK - Position heads over a specified cylinder Usage - Call BsDASeek(Drive$, Head%, Cylinder%, Rc%) Drive$ Letter designation of the target drive Head% Head to be positioned Cylinder% Cylinder over which the head will be positioned. Rc% Return code Programming notes: This service will not function on a diskette drive. It is intended for use with a hard disk only. This service can be used to park your fixed disk See BSDSTAT for an explanation of return codes. Copyright (c) 1987, AJM Software -Page 55- The File Attribute Services Function Summary FLGTIM - Get file creation time FLGDAT - Get file creation date FLGVOL - Get volume label FLPDAT - Change file creation date and time FLPVOL - Change volume label FLATTR - Change file attributes Copyright (c) 1987, AJM Software -Page 56- FLGTIM - Get file creation time Usage - Call FlGTim(FlSpec$, FlTime$, Rc%) FlSpec$ Standard ASCIIZ file name FlTime$ File creation time in HH:MM:SS format Rc% Return code Programming notes: See function FLFIND for additional capabilities. An ASCIIZ string is the standard DOS filename followed by CHR$(0) FlTime$ must be initialized to 8 blanks prior to calling FLGTIM. If it is not properly initialized, a 'String Space Corrupt' error may occur. See Appendix D for valid return codes. Use FLFIND instead of FLGTIM whenever possible because it is tremendously faster. Copyright (c) 1987, AJM Software -Page 57- FLGDAT - Get file creation date Usage - Call FlGDat(FlSpec$, FlDate$, Rc%) FlSpec$ Standard ASCIIZ file name FlDate$ File creation date in MM-DD-YYYY format Rc% Return code Programming notes: See function FLFIND for additional capabilities. An ASCIIZ string is the standard DOS filename followed by CHR$(0) FlDate$ must be initialized to 10 blanks prior to calling FLGDAT. If it is not properly initialized, a 'String Space Corrupt' error may occur. See Appendix D for valid return codes. Use FLFIND instead of FLGDAT whenever possible because it is tremendously faster. Copyright (c) 1987, AJM Software -Page 58- FLGVOL - Get volume label Usage - Call FlGVol(Drive$, Vol$) Drive$ Letter designation of drive Vol$ Volume label of the target drive Programming notes: Vol$ must be initialized to 11 blanks prior to calling FLGVOL. If it is not properly initialized, the entire volume label may not be returned in this field. No return code is provided for this function. If an invalid Drive letter is passed or if the target drive does not have a volume label, the con- tents of Vol$ will remain unchanged. If Drive$ is initialized to nulls (i.e. Drive$ = ""). The volume label of the default drive is returned. Copyright (c) 1987, AJM Software -Page 59- FLPDAT - Change file creation date and time Usage - Call FlPDat(Flspec$, FlDate$, FlTime$, Rc%) FlSpec$ Standard ASCIIZ file name FlDate$ File creation date in MM-DD-YYYY format FlTime$ File creation time in HH:MM:SS format Rc% Return code Programming notes: See function FLFIND for additional capabilities. An ASCIIZ string is the standard DOS filename followed by CHR$(0) FlDate$ must be initialized to a valid 10 character date prior to calling FLPDAT. If an invalid date is used or a date that is not 10 characters is used, FLPDAT will place garbage in the file creation date. This is not harmful to the date contained in the file, but may interfere with some MAKE or Backup processes. FlTime$ must be initialized to a valid 8 character time prior to calling FLPDAT. See discussion of FlDate$ for implications of using invalid times. See Appendix D for valid return codes. Copyright (c) 1987, AJM Software -Page 60- FLPVOL - Change volume label Usage - Call FlPVol(Drive$, Vol$, Rc%) Drive$ Letter designation of drive Vol$ Volume label to be written to target drive Rc% Return code Programming notes: Vol$ must be initialized to an 11 character string before calling FLPVOL. If it is not properly initialized, an incorrect volume label may be writ- ten to the disk. See Appendix D for return codes. If Drive$ is initialized to nulls (i.e. Drive$ = ""). The volume label of the default drive is updated. Copyright (c) 1987, AJM Software -Page 61- FLATTR - Change file attributes Usage Call FlAttr(FlSpec$, Mode%, Attr%, Rc%) FlSpec$ Standard ASCIIZ file name Mode% 0 - Get attributes 1 - Set attributes Attr% New file attributes (if Mode% = 1) or current file attributes (if Mode% = 0). Rc% Return code Programming notes: See function FLFIND for additional capabilities. An ASCIIZ string is the standard DOS filename followed by CHR$(0) Attr% is an integer between 0 and 63. Attributes are bit settings within this number and they are represented as: Normal 0 Readonly 1 Hidden 2 System 4 Volume 8 Subdir 16 Archive 32 The following code segment will interpret the Attr% field. FlSpec$ = "command.com"+chr$(0) 'Target filename Mode% = 0 'Indicate get attributes Call FlAttr(FlSpec$, Mode%, Attr%, Rc%) If Rc% <> 0 then goto Error.Routine 'Non-zero indicates failure If Attr% = 0 then Normal% = -1 'zero indicates no special Goto Print.Attr 'attributes End if FRead% = (Attr% and 1) = 1 'Check for readonly attr FHidden% = (Attr% and 2) = 2 'Check for hidden attr Copyright (c) 1987, AJM Software -Page 62- FSystem% = (Attr% and 4) = 4 'Check for system attr FVolume% = (Attr% and 8) = 8 'Check for Volume label FSubdir% = (Attr% and 16) = 16 'Check if its a sub-directory FArcive% = (Attr% and 32) = 32 'Check if its been archived Print.Attr: Attributes$ = "" If Normal% then Attribute$ = "Normal " If FRead% then Attribute$ = "Read Only " If Fhidden% then Attribute$ = Attribute$ + "Hidden " If Fsystem% then Attribute$ = Attribute$ + "System " If FSubdir% then Attribute$ = Attribute$ + "Directory " If FArcive% then Attribute$ = Attribute$ + "Archive" Print "FlSpec$", Attribute$ A program segment in the Sample programs (Registered copies only) shows how to initialize Attr% to set attributes. Copyright (c) 1987, AJM Software -Page 63- The File Access Services Function Summary FLOPEN - Open a file FLCLOS - Close a file FLREAD - Read a record from a file FLWRIT - Write a record to a file FLPOINT - Point to a specific record in a file FLCREAT - Create a file FLDELETE - Delete a file FLRSECT - Read a sector FLWSECT - Write a sector Copyright (c) 1987, AJM Software -Page 64- FLOPEN - Open a file Usage - Call FlOpen(FlSpec$, Mode%, Share%, Handle%, Rc%) FlSpec$ Valid ASCIIZ file name Mode% Specifies the use mode - valid values are: 0 - Read only access 1 - Write only access 2 - Read/Write access Share% Specifies the file sharing mode in multi-tasking envi- ronments. Valid values are: 1 - exclusive use 2 - allow read access only 3 - allow write access only 4 - allow read/write access(full sharing) Handle% Token returned by DOS to identify the opened file. Rc% Return code Programming notes: See Appendix D for an explanation of return codes. Share% is valid only for DOS 3.XX. DOS 2.XX users should always have Share% = 0. This service will open a file with normal, system, or hidden attribute. Handle% is an integer that DOS uses to identify the file. Most of the other services in this section of the manual require that Handle% be passed to then. After an open is successfully completed, the current record pointer is set at the start of the file. Copyright (c) 1987, AJM Software -Page 65- FLCLOS - Close a file Usage - Call FlClos(Handle%, Rc%) Handle% Handle of the file being closed. Rc% Return code Programming notes: See Appendix D for an explanation of return codes. Handle% is the token returned by FLOPEN. Any file opened with FLOPEN must be closed with FLCLOS. Initializing Handle% improperly may have some unpredictable results, such as locking the keyboard or disabling the printer and/or monitor. Copyright (c) 1987, AJM Software -Page 66- FLREAD - Read a record from a file Usage - Call FlRead(Handle%, Databuf$, Buflen%, Rc%) Handle% Handle of the file being read. Databuf$ Data area where the record will be placed after success- ful completion of the read. Buflen% Number of bytes to read. FLREAD will return the actual number of bytes read. Rc% Return code Programming notes: See Appendix D for an explanation of return codes. FLREAD returns the record being pointed to by the current record pointer. After a successful read, FLREAD will update the current record to point to the next record in the file. Initialize Buflen% to the number of bytes that you would like to read. FLREAD will update this field with the actual number of bytes read. When Buflen% is zero, or when it is less than it's initial value, end-of-file has been reached. It is the programmer's responsibility to insure that Databuf% is long enough to accommodate the record read from disk. If it is not initialized properly, a 'String Space Corrupt' error will probably occur. The follow- ing section of code shows a method of initializing Databuf$. Buflen% = 512 'Number of bytes to read Databuf$ = Space$(Buflen%) 'Create an adequate buffer Copyright (c) 1987, AJM Software -Page 67- FLWRIT - Write a record to a file Usage - Call FlWrit(Handle%, Databuf$, Buflen%, Rc%) Handle% Handle of the file being written to. Databuf$ Data area containing the record to be written. Buflen% Number of bytes to write. Rc% Return code Programming notes: See Appendix D for an explanation of return codes. FLWRIT writes the record at the position pointed to by the current record pointer. After a successful write, FLWRIT will update the current record to point the next record in the file. Initialize Buflen% to the number of bytes that you would like to write. FLWRIT will update this field with the actual number of bytes written. When Buflen% is zero, or when it is less than it's initial value, a disk full condition has been reached. Copyright (c) 1987, AJM Software -Page 68- FLPOINT - Point to a specific record in a file Usage - Call FlPoint(Handle%, Recno%, Reclen%, Rc%) Handle% Handle of the file being operated on. Recno% Record number that you would like to point to (relative to the beginning of the file). Reclen% Length of a logical record. Rc% Return code Programming notes: See Appendix D for an explanation of return codes. DOS will use Recno% and Reclen% to compute the offset of the record within the file. This service updates the current record pointer. Specifying Recno% = 0 will position you at the beginning of the file. Specifying Recno% = -1 will position you at the end of the file (Useful for adding records to the end of a file). DOS does not perform boundary checks on this function, so specifying Recno% or Reclen% improperly may set the current record pointer outside the limits of the file. Copyright (c) 1987, AJM Software -Page 69- FLCREAT - Create a file Usage Call FlCreat(FlSpec$, Mode%, Attr%,, Handle%, Rc%) FlSpec$ Valid ASCIIZ filename (except for Mode% = 2) Mode% Indicates open actions: 0 = Create the file if it doesn't exist - if it does exist, truncate the file. 1 = Create the file if it doesn't exist - if it does exist this service will fail 2 = Create a temporary file with a unique file name Handle% Handle assigned by DOS to the file Attr% File attributes assigned to this file. Rc% Return code Programming notes: See Appendix D for an explanation of return codes. See the documentation on FLATTR for an explanation of what to put in Attr% When Mode% is 2 Dos will create a temporary file and the name of the file will be returned in FlSpec$. These files are not automatically deleted when the program terminates. That is the responsibility of the program- mer. When a file is created, it is automatically opened for read/write access. No subsequent open is required to access the file, but you must close the file before the program terminates. When Mode% is 2 FlSpec$ must be initialized properly prior to calling FLCREAT. It should consist of an ASCIIZ path name followed by 12 blanks. For example: FlSpec$ = Chr$(0) + Space$(12) 'Current directory FlSpec$ = "C:\" + Chr$(0) + Space$(12) 'Root directory FlSpec$ = "\TEMP" + Chr$(0) +Space$(12) '\TEMP directory Copyright (c) 1987, AJM Software -Page 70- FLDELETE - Delete a file Usage FlDelete(FlSpec$, Rc%) Flspec$ Valid ASCIIZ filename Rc% Return code Programming notes: See Appendix D for an explanation of return codes. FlSpec$ may not use wildcard characters. This service should be used to delete files created using Mode% = 2 with FLCREAT (close it first before deleting it). Copyright (c) 1987, AJM Software -Page 71- FLRSECT - Read a sector Usage - Call FlRSect(Numsect%, Databuf$, Sector%, Rc%) Numsect% Number of sectors to read Databuf$ Data area where the data will be placed after successful completion of the read. Sector% Sector where read operation will start Rc% Return code Programming notes: Databuf$ must be long enough to hold the data read by this service. If it is not, you will probably get a 'String Space Corrupt' error. Sectors are generally 512 bytes. You can find out by using FLDSTAT - explained later in the manual. Sector% is the relative sector from the beginning of the disk, starting with sector 0. A return code of 0 indicates successful completion. There are a large number of return codes that can indicate failure. These will not be docu- mented here - if you really need them, write and we will gladly send them to you. If you are reading more than one sector, the sectors will be retrieved sequentially starting at Sector%. e.g. if Sector% = 5 and Numsect% = 3, then this service will read sectors 5,6,an 7. Copyright (c) 1987, AJM Software -Page 72- FLWSECT - Write a sector Usage - Call FlWSect(Numsect%, Databuf$, Sector%, Rc%) Numsect% Number of sectors to written Databuf$ Data area containing the data to be written. Sector% Sector where write operation will start Rc% Return code Programming notes: Sector% is the relative sector from the beginning of the disk, starting with sector 0. A return code of 0 indicates successful completion. There are a large number of return codes that can indicate failure. These will not be docu- mented here - if you really need them, write and we will gladly send them to you. If you are writing more than one sector, the sectors will be written sequentially starting at Sector%. e.g. if Sector% = 5 and Numsect% = 3, then this service will write sectors 5,6,an 7. ************************** IMPORTANT *********************************** Indiscriminate use of this function can cause serious problems with youR disk. Accidentally writing over the boot sector or the FAT (See the dis- cussion on disks in QBWARE.DOC Appendix C - found in QBWARE.ARC) can destroy all of the data on your disk. TAKE A BACKUP before testing this service, especially if you a writing to a HARD DISK. Copyright (c) 1987, AJM Software -Page 73- DOS Replacement Services Function Summary FLFIND - Find a file or group of files FLCNT - Count the number of matching files FLMOVE - Move a file FLCOPY - Copy a file to another file FLSDRV - Set the current drive FLGDRV - Get the current drive FLCDIR - Change the current directory FLGDIR - Get the current directory FLMDIR - Make a directory FLDDIR - Delete a directory FLDSTAT - Retrieve disk statistics Copyright (c) 1987, AJM Software -Page 74- FLFIND - Find a file or group of files Usage - Call FlFind(FlSpec$, Dirlist$(0)) FlSpec$ Standard ASCIIZ filename Dirlist$(0) Array containing all files matched by FlSpec$ Programming notes: FLFIND will return a list of all files in the current directory that match FlSpec$. Wildcards can be used. Each entry in Dirlist$ must be initialized to 40 blanks. If each element is not properly initialized, a 'String Space Corrupt' error may occur. Dirlist$ must be properly dimensioned so that all files matching FlSpec$ can fit into the array. If it is not properly dimensioned, unpredictable results can occur (probably 'String Space Corrupt', but anything can hap- pen). Use FLCNT to properly dimension the array. FLFIND can be used to determine the presence or absence of a file. See LOOK.BAS in the sample programs (registered users only) for an example of using FLCNT and FLFIND. This program will search an entire disk look- ing for matches (Wildcards are okay to use with LOOK.BAS). Each element of dirlist will have several items related to the matched files in it. The following program segment illustrates the proper use of FLFIND. FlSpec$ = "*.*"+chr$(0) 'Complete file directory call flcnt(FlSpec$, Count%) 'Get a count of matching files Dim Dirlist$(Count%-1) 'Dimension the array to FLFIND 'Subtract 1 for Option Base 0 For x%=0 to ubound(Dirlist$) 'Initialize each element of array Dirlist$(x%) = space$(40) 'to 40 blanks Next Copyright (c) 1987, AJM Software -Page 75- Call FlFind(FlSpec$, Dirlist$(0)) ' Each element of the array will be broken down into components ' The layout of each item is: ' Pos. Description ' 1-5 File Attributes ' 6-13 File creation time (HH:MM:SS) ' 14-23 File creation date (MM-DD-YYYY) ' 24-25 Low order file size ' 26-27 High order file size ' 28-39 File name For x% = 0 to Ubound(Dirlist$) if Dirlist$(x%) <> space$(50) then xfname$ = mid$(Dirlist$(x%),28,12) fattr$ = mid$(Dirlist$(x%),1,5) ftime$ = mid$(Dirlist$(x%),6,8) fdate$ = mid$(Dirlist$(x%),14,10) fsize1# = cvi(mid$(Dirlist$(x%),26,2))*65536 fsize2# = cvi(mid$(Dirlist$(x%),24,2)) if fsize2# < 0 then fsize2# = 65536 + fsize2# end if fsize# = fsize1# + fsize2# cls locate 1,1 print xfname$ print fattr$, "Attributes" print fdate$, "Creation date" print ftime$, "Creation time" print fsize#, "File size" locate 23,1 print "Press any key to continue" x$ = "" while x$ = "" x$ = inkey$ wend end if next Copyright (c) 1987, AJM Software -Page 76- FLCNT - Count the number of matching files Usage - Call(FlCnt(FlSpec$, Count%) FlSpec$ Standard ASCIIZ filename Count% Number of files matching FlSpec$ Programming notes: FLCNT will return a count of all files in the current directory that match FlSpec$. Wildcards can be used. FLCNT can be used to determine the presence or absence of file. FLCNT should be used prior to calling FLFIND to ensure that the passed array is large enough. See LOOK.BAS in the sample programs (registered users only) for an example of using FLCNT and FLFIND. This program will search an entire disk look- ing for matches (Wildcards are okay to use with LOOK.BAS). Copyright (c) 1987, AJM Software -Page 77- FLMOVE - Move a file Usage - Call FlMove(Old.FlSpec$, New.FlSpec$, Rc%) Old.FlSpec$ Standard ASCIIZ filename New.FlSpec$ Standard ASCIIZ filename Rc% Return code Programming notes: New.FlSpec$ can be any valid DOS filename that is not currently in use. You may specify a different directory, but you cannot move a file to a different device. Wildcards are not allowed. (A DOS wildcard is an '*' or a '?') See Appendix D for an explanation of return codes. Copyright (c) 1987, AJM Software -Page 78- FLCOPY - Copy a file to another file Usage - Call FlCopy(Old.Flspec$, New.Flspec$, Rc%) Old.FlSpec$ Standard ASCIIZ filename New.FlSpec$ Standard ASCIIZ filename Rc% Return code Programming notes: New.FlSpec$ must be a valid DOS filename. If it already exists, it will be overwritten. This function is somewhat slower than the DOS copy command. If a faster copy is needed, modify the Assembly source code to provide a larger buf- fer (registered users only). See Appendix D for an explanation of return codes. Copyright (c) 1987, AJM Software -Page 79- FLSDRV - Set the current drive Usage - Call FlSDrv(Drive$) Drive$ Drive letter designation Programming notes: This service does not return a completion code. It is up to the program- mer to insure that Drive$ is a valid drive designation (See FlGDrv to determine the number of drives). Copyright (c) 1987, AJM Software -Page 80- FLGDRV - Get the current drive Usage - Call FlGDrv(Drive$, Max.Drive$) Drive$ Drive letter designation Max.Drive$ Letter of the highest drive designation that Dos will recognize. Programming notes: Drive$ must be initialized to a single blank. If it is not properly ini- tialized, this service will not function and a 'String Space Corrupt' error may occur. Max.Drive$ is the highest letter designation that DOS will recognize. DOS assigns drive designators sequentially, so generally, if Max.Drive$ = 'D', that should mean that drives A,B, and C are valid. On some machines, Max.Drive$ may not be a valid drive. It may be the drive specified by the LASTDRIVE parameter of your CONFIG.SYS file. For consistent accurate results with this function, properly set LASTDRIVE in your CONFIG.SYS file. Copyright (c) 1987, AJM Software -Page 81- FLCDIR - Change the current directory Usage - Call FlCDir(Dir$, Rc%) Dir$ Valid directory name (ASCIIZ string) Rc% Return code Programming notes: See Appendix A for an explanation of return codes. Dir$ must be a valid directory name preceded by a '\' and followed by a Chr$(0) Copyright (c) 1987, AJM Software -Page 82- FLGDIR - Get the current directory Usage - Call FlGDir(Dir$) Dir$ Valid directory name (ASCIIZ string) Programming notes: Dir$ must be initialized to 64 blanks prior to calling FLGDIR. If it is not initialized properly, a 'String Space Corrupt' may result. The current directory is returned in Dir$. It is not preceded by a '\'. Copyright (c) 1987, AJM Software -Page 83- FLMDIR - Make a directory Usage - Call FlMDir(Dir$, Rc%) Dir$ Valid directory name (ASCIIZ string) Rc% Return code Programming notes: See Appendix D for an explanation of return codes. Dir$ must be a valid directory name preceded by a '\' and followed by a Chr$(0) Copyright (c) 1987, AJM Software -Page 84- FLDDIR - Delete a directory Usage - Call FlDDir(Dir$, Rc%) Dir$ Valid directory name (ASCIIZ string) Rc% Return code Programming notes: See Appendix D for an explanation of return codes. Dir$ must be a valid directory name preceded by a '\' and followed by a Chr$(0) Copyright (c) 1987, AJM Software -Page 85- FLDSTAT - Retrieve disk statistics Usage - Call FlDStat(Drive$, Type%, Bytes.Sector%, Sector.Cluster%, _ Avail.Cluster%, Total.Cluster%, Rc%) Drive$ Valid letter drive designation Type% Type of drive Bytes.Sector% Number of bytes in a sector on the target disk Sector.Cluster% Number of sectors in a cluster on the target disk Avail.Cluster% Number of unused clusters on the target drive Total.Cluster% Number of clusters on the target drive Rc% Return code Programming notes: See Appendix D for an explanation of return codes. Type% will indicate the type of drive. Possible values are: 255 - DSDD 8 Sectors/Track 254 - SSDD 8 Sectors/Track 253 - DSDD 9 Sectors/Track 252 - SSDD 8 Sectors/Track 249 - HD 15 Sectors/Track 248 - Fixed disk Most RAM drives will appear to be a fixed disk. Available space on the disk can be computed by the formula: Bytes.Sector% * Sector.Cluster% * Avail.Cluster% Total space on the disk can be computed by the formula: Bytes.Sector% * Sector.Cluster% * Total.Cluster% Copyright (c) 1987, AJM Software -Page 86- Miscellaneous DOS Services Function Summary BOOT - Initiate a cold or warm boot DOSCHOUT - Write a string to the standard output device DOSCHRIN - Read a character from the standard input device DOSSTRIN - Read a string from the standard input device DOSRED - Redirect a DOS standard handle DOSPRSC - Print the screen DOSVER - Get the DOS version DOSVRFY - Turn verify mode on and off Copyright (c) 1987, AJM Software -Page 87- BOOT - Initiate a cold or ward boot Usage - Call Boot(Function%) Function% 0 - Perform a warm boot 1 - perform a cold boot Programming notes: There is no return from this function - it restarts the machine. A warm boot is the equivalent of pressing Alt-Ctrl-Del - a cold boot is the equivalent of turning the machine off and then on again. Copyright (c) 1987, AJM Software -Page 88- DOSCHOUT - Write a string to the standard output device Usage - Call DosChOut(Str.Out$) Str.Out$ Text to be written Programming notes: If the standard output device is CON (monitor), the text is written to the current cursor location. Printing control characters(i.e. carriage return, line feeds) will cause the cursor to move accordingly. All data is written in 'raw' mode - this bypasses certain checking that DOS normally would do and increases output speed a little. Do not print chr$(255) as this will cause a keyboard read to occur. This service, like the other DOS keyboard/con services, can be re-directed. Copyright (c) 1987, AJM Software -Page 89- DOSCHRIN - Read a character from the standard input device Usage - Call DosChrIn(Char.In$, Echo%, Rc%) Char.In$ Character returned from the standard input device. Echo% 0 - do not echo to standard output 1 - echo to standard output Rc% 0 - indicates no character was found 1 - indicates character returned in Char.In$ 2 - indicates an extended ASCII character was returned in Char.In$ Programming notes: Extended ASCII characters will not echo. No special action is taken if Ctrl-C or Ctrl-Break is detected. Char.In$ must be initialized to a space. If it is not, the service will fail and a "String Space Corrupt' condition may occur. If an extended ASCII code is entered, Char.In$ will contain the second character of the code. This service, like the other DOS keyboard/con services, can be re-directed. Copyright (c) 1987, AJM Software -Page 90- DOSSTRIN - Read a string from the standard input device Usage - Call DosStrIn(Text.In$, Count%) Text.In$ input string Count% length of input string Programming notes: Use this function only for input of a single string on a screen. The editing characteristics of this service do not lend themselves to full screen input. No extended ASCII codes are allowed by this function. The maximum input length is the length of Text.In$ - 3. For example, if you wanted input with a maximum length of 12 characters, use the following code: Text.In$ = Space$(15) 'Maximum length + 3 call DosStrIn(Text.In$, Count%) End of input is signaled by pressing the [Enter] key. If you type in more than the maximum number of characters, the beep will sound until [Enter] is pressed. No cursor will be displayed while characters are being entered. The characters entered at the keyboard will echo on the monitor at the current cursor position. This service, like the other DOS keyboard/con services, can be re-directed. Copyright (c) 1987, AJM Software -Page 91- DOSRED - Redirect a DOS standard handle Usage - Call DosRed(Device%, FileSpec$, Rc%) Device% Device to redirect 0 - Standard input 1 - Standard output 3 - Standard AUX device 4 - Standard list device Filespec$ Standard ASCIIZ string Rc% Return code Programming notes: See the Appendix D for an explanation of return codes. The standard input device is CON, or the keyboard. If you redirect this device to accept from a file, you cannot detect end-of-file. If you play with this device, be prepared to reboot quite a bit while testing - incor- rect handling can easily cause the keyboard to lock up. The standard output device is CON, or the monitor. You can redirect this device either to a file or printer. Once redirected, all PRINT statements will print to FileSpec$. See the sample program TYPER.BAS included with this package. The standard auxiliary device is AUX - generally COM1. The standard list device is PRN - generally LPT1. Unfortunately, Basic does not use the standard list device for LPRINT statements or for PRINT# statements, thereby making redirection of this handle a little less useful than it could be. If FileSpec$ is NUL (i.e. FileSpec$ = ""), DOSRED will reset the device to its default value. these are: Device% Default 0 CON 1 CON 3 AUX 4 PRN If FIleSpec$ is CHR$(255), DOSRED will simply close that handle. This is useful if you're not using DOS 3.3 and you need more than fifteen files open at one time (the Quickbasic limit). Simply close one of the devices, and that allows you to open another file. If you close the standard input Copyright (c) 1987, AJM Software -Page 92- device, be sure to reopen it as you won't be able to get any input from the keyboard. Rumor has it that under DOS 3.3, you can have up to 255 files open at any one time. If FileSpec$ is a disk file, and it already exists, DOSRED will simply write over it. If it does not exist, DOSRED will create it. You must close any disk files used for redirection before terminating your program. Otherwise, the file's directory entry (length) will not be updated and you will not be able to process that file. A file close is done automatically when you issue a reset (FileSpec$ = ""). Copyright (c) 1987, AJM Software -Page 93- DOSPRSC - Print the screen Call DosPrSc Programming notes: This service will print the contents of the screen buffer. It is really a BIOS service, but because of it's usefulness, it is included here. Copyright (c) 1987, AJM Software -Page 94- DOSVER - Get the DOS version Usage - Call DosVer(Version%) Version% the version of DOS currently running Programming notes: Version is returned as an integer. DOS 3.10 would be returned as 310, and so on. To display it properly, use the following code: Call DosVer(Version%) Print Using "#.##";Version%/100 Copyright (c) 1987, AJM Software -Page 95- DOSVRFY - Turn verify mode on and off Usage - Call DosVrfy(Function%) Function% 0 - turn verify off 1 - turn verify on -1 - get status of verify Programming notes: When verify is on, every write request made through DOS will cause DOS to reread the sector just written to insure that it is readable. No verification is done when BIOS is used to write a sector. DOS does NOT perform a verify by checking that the sector written matches the data in the output buffer. It simply insures that the sector written can be read and that it passes the CRC. Verify does add overhead when it is turned on. Use this service when the output media is questionable. When using Function% = -1, DOSVRFY will return a 0 in Function% if Verify is off and a 1 if Verify is on. Copyright (c) 1987, AJM Software -Page 96- The Print Spooler YOU MUST HAVE VERSION 3.XX OF DOS TO USE THESE SERVICES Function Summary DOSPSTAT - Request spooler status DOSPCAN - Cancel all spooled files DOSPDEL - Delete a file from the queue DOSPLST - List all files in the queue DOSPSUB - Submit a file to the queue Copyright (c) 1987, AJM Software -Page 97- DOSPSTAT - Request spooler status Usage - Call DosPStat(Rc%) Rc% 0 - Normal status - okay to use spooler 1 - Spooler is inactive 2 - Spooler unavailable 255 - Invalid request (invalid DOS version) Programming notes: This service simply provides the spooler status. Each service in this section also checks the spooler status. The only good return code is 0. Any of the other return codes indicate that the spooler is not useable. A return code of 1 indicates the spooler is not running, but it could be started from the DOS prompt. A return code of 2 indicates that the spooler is not active and it cannot be started because some other process has captured the spooler interrupt. A return code of 255 indicates that the wrong version of DOS is installed - version 3.00 or higher is needed. See Appendix E for a discussion on starting the print spooler. Copyright (c) 1987, AJM Software -Page 98- DOSPCAN - Cancel all spooled files Usage - Call DosPCan(Rc%) Rc% Return code Programming notes: See Appendix E for an explanation of return codes. This service will delete all files from the print queue. Please remember that most printers have a print buffer - some as large as 256k. This function will not clear the print buffer. Copyright (c) 1987, AJM Software -Page 99- DOSPDEL - Delete a file from the queue Usage - Call DosPDel(FileSpec$, Rc%) Filespec$ ASCIIZ string Rc% Return code Programming notes: Filespec$ should be the name of a file in the print queue in ASCIIZ for- mat. ASCIIZ format is simply the file name followed by a CHR$(0), for example: Filespec$ = "C:\SPOOLDIR\TEXTFILE.DAT" +CHR$(0) You must use the entire filename (including drive and path) when deleting a file from the queue. See Appendix E for an explanation of return codes. This service will delete a files from the print queue. Please remember that most printers have a print buffer - some as large as 256k. This function will not clear the print buffer, so if the deleted file is print- ing, it will continue to print until the buffer is emptied. Copyright (c) 1987, AJM Software -Page 100- DOSPLST - List all files in the queue Usage - Call DosPLst(File.Array$(0), Rc%) File.Array$ Array that will contain the names of all the files in the print queue Rc% Return code Programming notes: See Appendix E for a explanation of return codes. File.Array$ must be initialized and have the proper number of elements prior to calling DOSPLST. Failing to initialize it properly will cause DOSPLST to fail and probably freeze up your computer. The maximum number of entries depends on what parameters were used when the print spooler was started. The absolute maximum is 32. I would strongly recommend that you plan for the maximum. The following code seg- ment shows the proper method of using DOSPLST. MaxQueue% = 31 'This is really 32 entries when 'using Option Base 0 Dim File.Array$(MaxQueue%) 'plan for max number of entries For X% = 0 to MaxQueue% 'initialize the array File.Array$ = Space$(64) 'max length of a filename Next Call DosPLst(File.Array$(0), Rc%) 'go get list If Rc% <> 0 then goto YOUR.ERROR.ROUTINE Copyright (c) 1987, AJM Software -Page 101- DOSPSUB - Submit a file to the queue Usage - Call DosPSub(FileSpec$, Rc%) FileSpec$ ASCIIZ string Rc% Return code Programming notes: FileSpec$ is the name of the file to be submitted to the print queue. See Appendix E for an explanation of return codes. The file is placed at the tail of the print queue. It will not print until all other files ahead of it have already printed. There is no way of prioritizing the files with the services presented here. Copyright (c) 1987, AJM Software -Page 102- DOS Memory Management PLEASE READ APPENDIX F BEFORE USING ANY OF THESE SERVICES Function Summary DOSMALLC - Allocate additional memory DOSMFREE - Free memory DOSMGET - Get some data from allocated memory DOSMPUT - Put some data in allocated memory Copyright (c) 1987, AJM Software -Page 103- DOSMALLC - Allocate additional memory Usage - Call DosMAllc(Block, MemSize%, Element.Size%, Rc%) Block% Reserved for future use MemSize% Amount of memory to acquire (in Kilobytes) valid ranges are 1-64 Element.Size% Size of each array element. Rc% Return code Programming notes: See Appendix F before using this service. Return code is explained in Appendix F. MemSize% is the memory size in KB - 64 would get 64,000 additional bytes. The area of memory returned by this service is initialized to nulls - CHR$(0). Only 1 area of memory can be allocated at any one time. If this service is attempted twice without an intervening call to DOSMFREE, the second call to DOSMALLC will fail. This service is the equivalent of the BASIC function DIM when used with a dynamic array. Copyright (c) 1987, AJM Software -Page 104- DOSMFREE - Free memory Call DosMFree(Block%, Rc%) Block% Reserved for future use Rc% Return code Programming notes: See Appendix F before using this service. Return code is explained in Appendix F. This service will free all memory obtained with DOSMALLC. This service is the equivalent of the BASIC function ERASE when used with a dynamic array. Copyright (c) 1987, AJM Software -Page 105- DOSMGET - Get some data from allocated memory Usage Call DosMGet(Block%, Index%, Text$, Rc%) Block% Reserved for future use Index% Array element number to retrieve Text$ String that will contain the data returned from memory Rc% Return code Programming notes: See Appendix F before using this service. Return code is explained in Appendix F. Text$ must be initialized to the proper length prior to using this ser- vice. It's length must equal the value of Element.Size% used in DOSMALLC. Index% the offset into the array where the requested data resides. The minimum value for Index% is 0 - the maximum value is determined by the following formula: MaxIdx% = Int(Max.Size%/Element.Size% *1000) - 1 Copyright (c) 1987, AJM Software -Page 106- DOSMPUT - Put some data in allocated memory Usage Call DosMPut(Block%, Index%, Text$, Rc%) Block% Reserved for future use Index% Array element number where data will be placed Text$ String containing the data to be placed into the array Rc% Return code Programming notes: See Appendix F before using this service. Return code is explained in Appendix F. The length of Text$ cannot exceed the value of Element.Size%. Index% the offset into the array where the data will be placed. The minimum value for Index% is 0 - the maximum value is determined by the following formula: MaxIdx% = Int(Max.Size%/Element.Size% *1000) - 1 Copyright (c) 1987, AJM Software -Page 107- Appendix A Keyboard Scan Codes Decimal Character 3 NUL 15 Shft-tab 16-25 Alt+(Q,W,E,R,T,Y,U,I,O,P) 30-38 Alt+(A,S,D,F,G,H,J,K,L) 44-50 Alt+(Z,X,C,V,B,N,M) 59,68 F1-F10 71 Home 72 Up cursor 73 PgUp 75 Left cursor 77 Right cursor 79 End 80 Down cursor 81 PgDn 82 Ins 83 Del 84-93 Shft-(F1-F10) 94-103 Ctrl-(F1-F10) 104-113 Alt+(F1-F10) 114 PrtSc 115 Left cursor 116 Right cursor 117 End 118 PgDn 119 Home 120-131 Alt+(1,2,3,4,5,6,7,8,9,0,-,=) 132 PgUp Copyright (c) 1987, AJM Software -Page 108- Appendix B BASIC Colors Color code Color 0 Black 1 Blue 2 Green 3 Cyan 4 Red 5 Magenta 6 Brown 7 White 8 Gray 9 Light Blue 10 Light Green 11 Light Cyan 12 Light Red 13 Light Magenta 14 Yellow 15 High-Intensity White Notes: The only valid background colors are 0-7. Add 16 (sixteen) to the color to cause blinking. Copyright (c) 1987, AJM Software -Page 109- Appendix C About Disks and Diskettes DISK AND DISK FORMATS Hard disks and floppy disks essentially use the same format under DOS. There are four logical areas of interest on each disk - the boot sector, the FAT, the root directory and the data area. Physically, data is recorded on a series of tracks. Each track is further divided into areas called sectors. The physical capacity of each disk varies considerably from drive to drive. There are only two characteristics of disks that are fixed by hardware constraints - the number of sides and the location of each track on the disk. The size and number of sectors and their location within each track is totally under software control. Each of these characteristics is def- ined by the formatting software (the FORMAT program usually). We'll dis- cuss most of the DOS formats shortly. Sectors can be placed on a track in any order and in any combination of 4 sizes - 128, 256, 512 or 1024 bytes. Generally it is wise to use a sector size of 512 bytes because that's the standard and there are probably many programs, including DOS, that depend on a 512 byte sector size. There are several standard formats currently used by DOS. The following table summarizes each format and it's characteristics. Type Sides Sectors Tracks Bytes SSDD-8 1 8 40 160,000 DSDD-8 2 8 40 320,000 SSDD-9 1 9 40 180,000 DSDD-9 2 9 40 360,000 3 1/2 in. 2 9 80 720,000 DDHD 2 15 80 1,200,000 The most common of these formats is the DSDD-9, but with the introduction of laptops and the PS/2 line from IBM, the 3 1/2 in. diskettes will prob- ably become the standard of the future. When using the BIOS to access disks, it is important to understand their characteristics. Bios disk access routines require us to know three things about the particular sec- tor that we're looking for. These are the track number, the cylinder num- ber, and the sector number, The first track on a disk is always 0. Dis- kettes with 40 tracks will have them numbered 0 - 39. The cylinder number is sometimes called the side or head number. It really represents which side of the diskette we want to read, top or bottom. Cylinder is 0 for top or 1 for bottom. Hard disks may have more than two cylinders. Copyright (c) 1987, AJM Software -Page 110- Sector numbers always start with 1. Therefore, the first sector on a disk is always Track 0, Cylinder 0, Sector 1. As I said earlier, DOS organizes the disk into four areas. We'll examine each of these separately. The Boot Sector The boot sector contains a short program used to start the computer and it also contains the characteristics of the disk in an area called the BIOS parameter block. The short program does one of two things - it loads the three startup modules, IBMBIO.COM, IBMDOS.COM, and COMMAND.COM and trans- fers control to COMMAND.COM or it displays a message stating that the dis- kette is not a bootable one. The format of the boot sector is as follows: Location Description 0-2 Branch to first byte of boot code 3-29 BIOS parameter block 3-10 System ID 11-12 Number of bytes/sector 13 Number of sectors/cluster 14-15 Number of reserved sectors at beginning 16 Number of FAT's 17-18 Number of root directory entries 19-20 Total number of sectors on disk 21 Format ID 22-23 Number of sectors/FAT 24-25 Number of sectors/track 26-27 Number of cylinders 28-29 Number of special reserved sectors The rest of the boot program follows the BIOS parameter block. At the end of the boot record, we need the two-byte signature, a hex 55AA. The Root Directory The directory holds basic information about each file. There can, of course, be more than one directory, but there is only one root directory. Subdirectories have essentially the same format as the root directory, but there is one notable difference. A subdirectory is really another file - a special type of file. As a file, it can grow to virtually any size and have any number of entries (not totally true, but there are no PRACTICAL limits). The root directory is fixed in length and therefore can have Copyright (c) 1987, AJM Software -Page 111- only a limited number of entries. This is usually 64 or 112. Each entry in the directory uses 32 bytes, so we are limited to sixteen entries per sector. Each entry contains the following eight fields: Position Description 0-7 Filename 8-10 Filename extension 11 Attribute 12-21 Reserved 22-23 Last update time 24-25 Last update date 26-27 First FAT entry 28-31 File size The Data Area The data area is the largest area on the disk. It is where our files are actually placed. Space is allocated in units called clusters. A cluster is made up of one or more sectors. This is defined at disk format time. That all we need to know about the data area. THE FAT The FAT - file allocation table - keeps track of where our files physi- cally reside on disk. The directory entry for each file contains the address of the first sector that the file occupies. If the file occupies more than 1 sector, DOS keeps track of it in the FAT. There are generally two copies of the FAT on every disk. DOS updates both copies, but only uses one of them for file retrieval. FAT's have one of two formats - a 12 bit or a 16 bit format. The 12 bit format allows you to access just over 4,000 clusters, so it is used primarily in diskettes and the smaller hard disks. The 16 bit format allows us to access many more clusters and facilitate larger hard disks. It is because of the FAT entry size that we are limited, by DOS, to a maximum 32 Meg hard disk (although there are several programs, such as SPEEDSTOR by Storage Dimensions, Inc. that do away with this limitation and in fact, some versions of DOS 3.3x also pro- vide work-arounds for this limit - the most notable being COMPAQ DOS 3.31). Each byte in the FAT represents a cluster and tells us the disposition of that cluster. The first two bytes in the FAT are reserved and are not used for this purpose. Copyright (c) 1987, AJM Software -Page 112- For illustration, we will use a 12 bit FAT. The allowable values in each entry are: Value Description 0 The cluster is unused and available for use 1-FF0(4080) A pointer to the next cluster that this file occupies. FF7(4087) The cluster has been flagged as unusable by FORMAT. This occurs when the format program cannot successfully write to one of the sectors in the cluster. FFE(4094) The cluster is not used but is unavailable for use. This occurs only when DOS reserves a cluster. FFF(4095) This indicates that this is the last cluster that a file occupies. As you can see, the FAT links together the clusters that make up a file. It is also easy to see that if the FAT becomes damaged, your disk or dis- kette becomes so much trash. In general, it's not a good idea to manipu- late the FAT unless your an experienced programmer. FORMATTING A DISKETTE Please keep in mind that these procedures are directed to a floppy disk only. In principle, formatting a hard disk is similar, but don't try it with these guidelines. Formatting a diskette is a four-step process. 1 Format each track of the diskette 2 Write the boot sector 3 Initialize the FAT 4 Initialize the root directory We can format each track of a diskette using the BsDFmt service provided in QBWARE/1. Note that this service requires the use of a 'track format table'. This table contains a 4-bytes descriptor for each sector being formatted. Individual sectors cannot be formatted. You must format an entire track with one BIOS call but the track format table lets us define the characteristics of each sector. The track format table looks like this: Byte 1 - track being formatted Byte 2 - Head being formatted Byte 3 - Sector being formatted Byte 4 - size code Copyright (c) 1987, AJM Software -Page 113- The size code has the following values: 0 128 byte sectors 1 256 byte sectors 2 512 byte sectors 3 1024 byte sectors The following program would format an entire DSDD-9 conventional diskette. DataBuffer$ = Space$(36) For Track% = 0 to 39 For Head% = 0 to 1 For Sector% = 1 to 9 Mid$(DataBuffer$,((Sector%-1)*4)+1) = _ Chr$(Track%)+Chr$(Head%)+Chr$(Sector%)+Chr$(2) Next Sector% Call BsDFmt(DataBuffer$,"A",Head%,Track%,9%,Rc%) Next Head% Next Track% Of course, this routine does not do any error checking. Once this has completed, we can continue to write the boot sector, FAT, and root directory. These are beyond the scope of this discussion, but if you need help in doing this, please drop me a note and I'll see what I can do. COPY PROTECTION Using the BIOS format service, we can devise our own copy protection schemes. These schemes are not as elaborate as the schemes used by some of the larger software houses (these actually use special hardware to put junk in places on a diskette that are read-only accessible to a standard floppy controller), but can be effective against the casual soft- ware pirate. The means available to us are: - leave out a sector number in the track format table - place a unique number in the track format table - format ten sectors on one or more tracks - change the sizes of one or more sectors on a track - format past track 39 - change the interleave Be careful, not all of these techniques work consistently with all floppy disk controllers. Copyright (c) 1987, AJM Software -Page 114- APPENDIX D Using the File Access Services All of the file access services use the DOS extended file services. These services call for the use of file handles - a UNIX concept. Because of this we are still limited to a maximum of 20 open files in any Quickbasic program. This includes the 5 standard files that DOS requires effectively limiting any Quickbasic program to 15 open files at any one time. This should normally be enough, however, if it becomes a problem, there are some facilities in QBWARE/1 that will allow you to open more than 15 files, but still we cannot exceed 20. If you must have more than 20 open files, you must use the old FCB style file services. This will allow you to access up to 255 files simultaneously. These routines are available from AJM Software and if you'd like them, just write (Note: DOS 3.3 will allow 255 open files, so, that's you're best bet). Using the file access services requires the use of an ASCIIZ string. This is simply a file name (or part of a file name) followed by a null. Some examples of ASCIIZ strings: FlSpec$ = "C:COMMAND.COM" + Chr$(0) Path$ = "\QUICKBAS" + Chr$(0) The standard error codes for all of the QBWARE/1 file management routines except FLRSECT and FLWSECT are as follows: Code Reason 0 service completed successfully 1 invalid request 2 file not found or path invalid 3 path not found 4 no handle available 5 access denied 6 invalid handle 12 invalid access code 15 invalid drive specification 17 not the same device (FLMOVE only) 18 no matching directory entry found 22 attempt to delete current directory 80 file already exists 255 invalid parameter Copyright (c) 1987, AJM Software -Page 115- Appendix E The Print Spooler Version 3.00 of DOS brought with it a remarkable new program - the print spooler. The spooler is remarkable because it allows you to print files in the background while the computer is free to do other tasks. It is somewhat limited in that it does automatically capture data going to the printer and spool it for you and it must be used from the DOS prompt. In order to use it, you must write your report to a file and subsequently go to the DOS prompt and submit it to the print queue - either manually or through a batch file. The services provided in QBWARE/1 will assist in incorporating the spooler into any Quickbasic system. You must still write each report to a file, but we can, with DOSPSUB, submit the file to the print queue directly from a Quickbasic program. In order to use QBWARE/1 spooler service, we must start the spooler before your Quickbasic basic program executes. The spooler can be started from the DOS prompt or from your AUTOEXEC.BAT file (any BAT file will do). The spooler program is called PRINT.EXE and is available on your DOS ver- sion 3.XX diskettes. When starting the spooler, there are several options that can be used. These are: /D Device that all files will be printed on - if omitted, the spooler will prompt you for a device name /Q Maximum number of files that can be in the print queue - the default is 4 and the absolute maximum that can be used is 32 /B Buffersize of the internal buffer used by the spooler - the default is 512 bytes - we always use 2048 bytes, but the correct value will depend on overall system usage /S Timeslice for the spooler - this defines the number of clock ticks that the spooler will use - the default is 8 and the values can range from 1-255 /M Specifies the maximum number of clockticks that the spooler will use to print a character - values can be 1-255 and the default is 2 /U Specifies the number of clockticks that the spooler will wait for the printer to become available - values can range from 1-255 and the default is 1 Copyright (c) 1987, AJM Software -Page 116- The command PRINT /D:LPT1 /B:2048 /Q:32 will activate the spooler with an internal buffer of 2048 bytes and cause all output to be spooled to LPT1. The maximum number of files that can be in the queue at one time is 32. Once this is completed, the routines in QBWARE/1 can be used. Return codes from the spooler are as follows: Rc Reason 0 Successful 1 Spooler inactive 2 Spooler inactive (DOSPSTAT only) 2 File not found 3 Path not found 4 Too many open files 5 Access denied 8 Queue full 9 Spooler busy 12 Name too long 15 Invalid drive 255 Invalid DOS version Copyright (c) 1987, AJM Software -Page 117- Appendix F Using the DOS Memory Services NOTE: If you are using QuickBasic V4, do not read this section. You can use the DOS Memory Service after shrinking memory within QuickBasic through the SETMEM function. If you're not using QB4 - read on!!!! General info The Dos Memory Services provided in QBWARE/1 will allow you to allocate an array of up to 64,000 characters in length. This array is handled like text data, but unlike BASIC, QBWARE/1 does not allow variable length strings. This data resides outside of the Quickbasic data segment, so it has no effect on the amount of string space normally provided by Quickba- sic. This array is handled a little bit differently than a Quickbasic array would be. Let's look at some examples. In Quickbasic, we could allocate an array and initialize a single element with the following code segment: Option Base 0 Dim Array$(400) Array$(0) = "This is the first element of the array" Using the services in QBWARE/1, we could do this: Mem.Size% = 64 'Allocate 64,000 bytes Element.Size% = 100 'Need element size because QBWARE/1 does not 'support variable length text Call DosMAllc(Block%, Mem.Size%, Element.Size%, Rc%) If Rc% <> 0 then Goto Error.Routine Text$ = "This is the first element of the array" Index% = 0 Call DosMPut(Block%, Index%, Text$, Rc%) Copyright (c) 1987, AJM Software -Page 118- In the Quickbasic example, we first allocate enough memory for 400 items in the array called Array$ (Note that this doesn't mean that you can actu- ally use all 400. If you tried to initialized each element of Array$ to 200 spaces, your program would run out of string space long before you completed the initialization). All this actually does is set aside 1600 bytes within Quickbasic. This 1600 bytes is used as a series of 'string descriptors' - you can read the Quickbasic manual for a discussion of string descriptors. Next, we assign a value to the first element in the array. Quickbasic allocates some space in it's own data segment for this value and updates the string descriptor accordingly. The descriptor con- tains the length of the string and it's location within the Quickbasic data segment. In the QBWARE/1 example, we first need to allocate some space. The amount of space needed is 64,000 characters, or bytes. This is done by setting Mem.Size = 64 Next, because QBWARE/1 will not support variable length text, we need to determine the length of each element. For all practical purposes, this is the length of the longest element that we will place into the array. Next we allocate space for the array using DOSMALLC. This service actually allocates the entire 64,000 bytes. In order to initialize on of the ele- ments of our new array, all we need do is specify the element number, or index, and the text itself - DOSMPUT will do the rest. Keep in mind that if the length of the Text$ that you're storing to the array is longer than Element.Size%, DOSMPUT will not store the data and it will pass a return code of 252 back to the calling program. If the length of Text$ is less or equal to than Element.Size%, DOSMPUT will store all of the text. Text$ can be retrieved from the array by using the same technique with DOSMGET. DOSMGET will always return a string of length Element.Size%. If the length of the original string stored with DOSMPUT was less than Ele- ment.Size%, DOSMGET will still return a string of length Element.Size%. The back end of the string will be padded with nulls (CHR$(0)). If you transfer control from the program that allocates memory to another Quickbasic program, you may still be able to use the array allocated in the first program. If the first program "CHAIN"'s to the second program, the array allocated in the first program will be intact - no data will be lost. Additionally, the special linking requirements explained later in this Appendix apply only to the first program. If, however, the first program "RUN"'s the second program, then the array allocated in the first program is lost. If the second program needs to allocate memory, then it must be linked using the guidelines discussed later in this Appendix. Copyright (c) 1987, AJM Software -Page 119- Who can use the memory allocation services? Memory is a severely limited resource in most computers from large IBM mainframes to the PC. Whether or not you can use the QBWARE/1 memory services depends on several factors. We'll discuss each of these factors in detail to help you decide whether or not QBWARE/1 is viable for you. The first constraint is the amount physical conventional memory installed on your computer - this does not include extended or expanded memory. The maximum amount of conventional memory that can be installed in any DOS computer is, of course, 640,000 bytes. The rules to follow here are: - If you have less than 256K of memory, you probably cannot run applications that use the QBWARE/1 memory services - If you have 256K of memory, you MIGHT be able to run these applications, but you probably cannot write your own applica- tions. The Quickbasic integrated development requires to much memory to allow testing. -If you have more than 256K of memory, you can probably run and test applications written with QBWARE/1 memory management facil- ities. Read on for further information. The next constraint is the amount of memory used by things other than Quickbasic. DOS requires a minimum of around 26K - and that is for a plain vanilla DOS. I generally install several drivers and have my files and buffers parameters set pretty high so DOS requires 55K on my machine. If you have a great deal of TSR's (SideKick for example) installed, you may be giving up a lot of memory to them - the more memory used by TSR's, the less available to Quickbasic and QBWARE/1. Both DOS and TSR's decrease the amount of memory available. If you're having a problem using QBWARE/1 and you have TSR's installed, try removing them. The next constraint is the amount of memory used by Quickbasic. The fig- ures presented here have been arrived at by analysis performed by us and in no way reflect any information received by Microsoft. There are sev- eral factors that determine the amount of memory that a Quickbasic program needs to execute. These are: - The amount of code that you write. Quickbasic needs about 68K of memory for the its' own routines. Any code that you write would be over and above this 68K. Copyright (c) 1987, AJM Software -Page 120- - The data area used by Quickbasic is always 64K - no more, no less. - The size of the user library increases memory requirement by the size of the code segments in the library. - Communication programs will require storage for buffers. This, of course, is allocated by the programmer. - All remaining memory gets allocated to the far heap. If you use large numeric arrays, they would be allocated here. This is the area of memory used by QBWARE/1. From this info, we can see that a very simple one-line Quickbasic program will need about 132K to run. An approximation of memory requirements can be calculated with: Data segment size 64K + QB runtime library 68K + Size of far arrays ?? + (1) User library code size ?? + (2) Size of EXE file ?? + (3) Size of communication buffers ?? + (4) = memory requirements Add about 124K if you're running programs out of the QB editor. For programs compiled with the /o option, do not include the QB runtime library size. (1) Far arrays are large numeric arrays defined in your program. You can determine size using the following: Integer arrays - Size = Number of elements * 2 Single precision - Size = Number of elements * 4 Double precision - Size = Number of elements * 8 (2) This is tough, but to be on the safe side, just use the size of your USERLIB.EXE file (or whatever your user library is named). (3) This is simply the size of the EXE file as reported by the DOS dir command. (4) This one is easy because you as the programmer allocate these with the /c:buffersize parameter. Copyright (c) 1987, AJM Software -Page 121- If, after adding these numbers together, we come up with a memory require- ment that is close to the size of memory installed in that computer, you probably cannot use the memory management facilities in QBWARE/1. If there is room in your program, read on (Remember, when you run a program from the Quickbasic editor, add about 124K). Preparing to use the memory allocation services When a Quickbasic program is linked, the linker tells DOS the minimum and maximum amounts of memory required by the program. When you execute the program, DOS will attempt to allocate the maximum amount of memory needed by the program. For Quickbasic programs, this maximum is always all of available memory. Before using the memory allocation services, we must first adjust the amount of memory that DOS allocates for the program. This can be done in three ways: 1) When linking your Quickbasic program, use the CP parameter to limit maximum memory size. You can tell the assembler how much memory to allocate in units of 16 byte paragraphs. For example, if we wanted a program to use 256k, we would link it like this: qb testprog; link testprog /cp:16000 We can determine the number of paragraphs by taking the memory size and dividing by 16 (256,000 / 16 = 16000) 2) For those of you who have Microsoft's MASM, you can use the EXEMOD utility. EXEMOD will do the same thing that the CP parameter of link does except that we must specify the paragraph count in Hexa- decimal. If we wanted a program to use 256k of memory, we could do this: qb testprog; link testprog; exemod testprog /max 4000 4000 is about the number of paragraphs, in hex, that we need to get 256K - it's actually a little high, but it's easier to remember than 3E80. 3) The program QBTMOD.BAS, provided with QBWARE/1, will change the maximum memory requirement to 256K. Source code is provided so you can modify it as you wish. Copyright (c) 1987, AJM Software -Page 122- Using the memory allocation services in the Quickbasic editor is a little trickier. We must take the following steps in order to do this. 1) Make a BACKUP of QB.EXE 2) Make another BACKUP of QB.EXE 3) Do one of the following: - EXEMOD QB /MAX 4000 (if you have EXEMOD) - QBTMOD QB /MAX 16000 This will allow you to execute DOSMALLC once while in the Quickbasic edi- tor. When you start Quickbasic, it will not allocate all of memory, how- ever, if you run a program (Ctrl-R) or SHELL from the editor, when you return to Quickbasic, it acquires all available memory. This means that you can only run DOSMALLC once while in the editor. If you need to run it again, you must first exit Quickbasic, and then start it again. This does cause some problems in debugging our programs, but if you need the additional string space and you don't have expanded memory, then your options are limited. Copyright (c) 1987, AJM Software -Page 123-